@opentelemetry/context-async-hooks

What is @opentelemetry/context-async-hooks?

The @opentelemetry/context-async-hooks package is part of the OpenTelemetry project, which provides a set of APIs, libraries, agents, and instrumentation to create and manage telemetry data (metrics, logs, and traces) for cloud-native software. Specifically, this package leverages Node.js' async_hooks module to implement context propagation for asynchronous operations. This is crucial for tracing and logging in asynchronous applications, as it allows developers to maintain context across asynchronous boundaries.

What are @opentelemetry/context-async-hooks's main functionalities?

Context Management

This feature allows for the management of context across asynchronous operations. It uses the AsyncLocalStorage class to create a new context storage, run a function within this context, and retrieve values from this context later in the async flow.

const { AsyncLocalStorage } = require('@opentelemetry/context-async-hooks');
const asyncLocalStorage = new AsyncLocalStorage();

asyncLocalStorage.run(new Map(), () => {
  asyncLocalStorage.getStore().set('key', 'value');
  someAsyncOperation().then(() => {
    console.log(asyncLocalStorage.getStore().get('key')); // Outputs: 'value'
  });
});

Context Propagation

This feature demonstrates how to set up the AsyncLocalStorageContextManager to work with OpenTelemetry's API for global context propagation. This setup is essential for tracing asynchronous operations across different parts of an application.

const { propagation } = require('@opentelemetry/api');
const { AsyncLocalStorageContextManager } = require('@opentelemetry/context-async-hooks');

const contextManager = new AsyncLocalStorageContextManager();
propagation.setGlobalPropagator(contextManager);

// Now, the context is propagated across asynchronous calls automatically.

Other packages similar to @opentelemetry/context-async-hooks

cls-hooked

The cls-hooked package provides a similar functionality to @opentelemetry/context-async-hooks by using the async_hooks module to create context-like namespaces that are preserved across asynchronous calls. It differs in its API and is not specifically tailored for OpenTelemetry or tracing but can be used for general context propagation purposes.

async_hooks

While not a separate npm package, Node.js' built-in async_hooks module is the underlying technology that both @opentelemetry/context-async-hooks and cls-hooked rely on for tracking asynchronous operations. It provides the primitives for creating hooks that monitor the lifecycle of asynchronous operations, which can be used directly for custom context propagation implementations.

README

OpenTelemetry AsyncHooks-based Context Manager

This package provides async-hooks based context manager which is used internally by OpenTelemetry plugins to propagate specific context between function calls and async operations. It only targets NodeJS since async-hooks is only available there.

What is a ContextManager

The definition and why they exist is available on the readme of the context-base package.

Implementation in NodeJS

NodeJS has a specific API to track async context: async-hooks, it allows to track creation of new async operation and their respective parent. This package only handle storing a specific object for a given async hooks context.

Limitations

Even if the API is native to NodeJS, it doesn't cover all possible cases of context propagation but there is a big effort from the NodeJS team to fix those. That's why we generally advise to be on the latest LTS to benefit from performance and bug fixes.

There are known modules that break context propagation (some of them are listed there), so it's possible that the context manager doesn't work with them.

Prior arts

Context propagation is a big subject when talking about tracing in NodeJS, if you want more information about that here are some resources:

• https://www.npmjs.com/package/continuation-local-storage (which was the old way of doing context propagation)
• Datadog's own implementation for their Javascript tracer: here
• OpenTracing implementation: here
• Discussion about context propagation by the NodeJS diagnostics working group: here

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.19.0

:boom: Breaking Change

• opentelemetry-core, opentelemetry-tracing
  • #2111 feat: handle OTEL_TRACES_SAMPLER env var (@jtmalinowski)
  • #2098 chore(env): update default value for span's attributes/links/events count #1675 (@vmarchaud)
• opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-semantic-conventions, opentelemetry-tracing, opentelemetry-web
  • #2083 feat: add semconv generator for semantic-conventions-package (@weyert)
• opentelemetry-core, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-sdk-node, opentelemetry-web
  • #2081 remove plugins (@obecny)
• opentelemetry-api-metrics, opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #2074 chore: peer depend on API (@dyladan)
  • #2063 chore: update API dependency to 1.0.0-rc.0 (@dyladan)
• opentelemetry-core, opentelemetry-propagator-b3
  • #2054 refactor: simplify b3 options (@mwear)

:rocket: (Enhancement)

• opentelemetry-instrumentation
  • #2135 fix: add isEnabled to InstrumentationBase (@seemk)
• opentelemetry-semantic-conventions
  • #2115 feat: upgrade semantic conventions to v1.2.0 of spec (@weyert)
• opentelemetry-core, opentelemetry-exporter-zipkin
  • #2097 feat(zipkin): allow to configure url via environment #1675 (@vmarchaud)
• opentelemetry-exporter-zipkin
  • #2050 chore: adding interceptor for getting headers before each request (@obecny)
• opentelemetry-exporter-collector-grpc
  • #2092 Migrate exporter-collector-grpc to grpc-js (@obecny)
• opentelemetry-instrumentation-http
  • #2043 chore: avoid unneeded context.with in http instrumentation (@Flarna)
• opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-xml-http-request
  • #2061 chore: adding info to debug whenever headers are being skipped due to cors policy (@obecny)

:bug: (Bug Fix)

• opentelemetry-exporter-prometheus
  • #2121 fix: ensure the label names are sanitised (@weyert)
• opentelemetry-instrumentation
  • #2120 fix(instrumentation): support multiple module definitions with different versions (@seemk)
• opentelemetry-instrumentation-http, opentelemetry-tracing
  • #2105 fix: don't use spanId from invalid parent (@Flarna)
• opentelemetry-context-async-hooks
  • #2088 fix: correct removeAllListeners in case no event is passed (@Flarna)
• opentelemetry-resource-detector-aws
  • #2076 fix: await http response in AWS EKS detector (@vreynolds)
• opentelemetry-core, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger
  • #2082 chore: do not inject span context when instrumentation is suppressed (@dyladan)
• opentelemetry-core
  • #2080 fix: do not inject invalid span context (@dyladan)
• opentelemetry-tracing
  • #2086 fix: exception.type should always be a string (@YanivD)
• opentelemetry-propagator-jaeger
  • #1986 fix(propagator-jaeger): zero pad extracted trace id to 32 characters (@sid-maddy)

:books: (Refine Doc)

• #2094 chore: fixing readme info (@obecny)
• #2051 Add opentelemetry.io docs (@austinlparker)

:house: (Internal)

• opentelemetry-exporter-collector-grpc, opentelemetry-metrics, opentelemetry-tracing
  • #1780 chore: no-floating-promises (@naseemkullah)
• opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-propagator-jaeger, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #2073 chore: pin own deps (@dyladan)

Committers: 15

• Anuraag Agrawal (@anuraaga)
• Austin Parker (@austinlparker)
• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Gerhard Stöbich (@Flarna)
• Jakub Malinowski (@jtmalinowski)
• Matthew Wear (@mwear)
• Naseem (@naseemkullah)
• Niek Kruse (@niekert)
• Siddhesh Mhadnak (@sid-maddy)
• Siim Kallas (@seemk)
• Valentin Marchaud (@vmarchaud)
• Vera Reynolds (@vreynolds)
• Weyert de Boer (@weyert)
• Yaniv Davidi (@YanivD)